home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE4 / ZAP / !Zap / Code / Extensions / ExtAsm / DebuggrDoc < prev    next >
Text File  |  2002-08-28  |  11KB  |  363 lines
  1. =============
  2. Debugger Plus
  3. =============
  4.  
  5. Version 2.09, 3 April 2002
  6. by Darren Salt <ds@youmustbejoking.demon.co.uk>
  7.  
  8.  
  9.  
  10. Introduction
  11. ============
  12.  
  13. This module provides a complete replacement for the standard Debugger module.
  14. It contains a much extended disassembler, and improved and extended
  15. *commands.
  16.  
  17. It is aware of all ARMs up to ARM8 and StrongARM SA110; it knows of all
  18. instructions up to ARM7, and the sign-extend and half-word load/store
  19. extensions. It also has a few extras thrown in (see below). It can also
  20. auto-detect which cache type is in use, since this is indicated by the ARM
  21. ID.
  22.  
  23. The module may be loaded using an *RMEnsure - which is why version numbering
  24. was started at 2.00 and not 0.xx or 1.xx. It is best loaded from
  25. !Boot.Choices.PreDesk; the standard distribution assumes this, and provides a
  26. directory to be placed in there. If your !Boot looks different, then you'll
  27. have to find somewhere else to put it; ideally, before the Desktop is started
  28. up.
  29.  
  30. It is possible to initialise the flags by appending them to the load command.
  31. For example:
  32.   *RMLoad <Obey$Dir>.Debugger -FDwithR13 Y -QuoteSWIs Y
  33. (If a flag is not specified, it defaults to OFF.)
  34.  
  35.  
  36. ** Note that the SWI interface has changed since version 2.04. This is to
  37.    provide compatibility with versions of the standard Debugger module which
  38.    can disassemble Thumb instructions.
  39.  
  40.  
  41. Commands supported
  42. ==================
  43.  
  44. The commands in this module try to avoid causing data aborts or address
  45. exceptions; the behaviour on encountering non-existent memory, unless
  46. otherwise specified, is to simply complain that there's no readable or
  47. writable (whichever is appropriate) memory at this address.
  48.  
  49. [Note: untested with StrongARM memory protection of zero-page vectors;
  50. comments welcome.]
  51.  
  52.  
  53. BreakSet, BreakClr, BreakList
  54. --------  --------  ---------
  55.  
  56. These work as standard.
  57.  
  58. Most PC-reading instructions (eg. LDR R0,[PC,#28]) when breakpointed, are not
  59. specially handled by *Continue, and it is therefore recommended that you do
  60. not place breakpoints on these instructions.
  61.  
  62. It is, however, safe to place breakpoints on the following instructions even
  63. when R15 is being read from:
  64.     B, BL
  65.     ADD, SUB
  66.     MOV
  67.     MUL, MLA
  68.     AND, EOR, RSB, ADC, ORR, BIC, SBC, RSC, MVN
  69.  
  70. This is mainly with the intention of supporting ADR and jump tables.
  71.  
  72. (The standard Debugger only supports B instructions.)
  73.  
  74.  
  75. Continue, InitStore
  76. --------  ---------
  77.  
  78. As standard.
  79.  
  80.  
  81. Memory
  82. ------
  83.  
  84. Has an extra mode, A, which displays memory as plain ASCII (64 columns wide);
  85. displays the 'contents' non-existent memory as strings of dots.
  86.  
  87.  
  88. MemoryI
  89. -------
  90.  
  91. Uses the extended disassembler, and displays the 'contents' non-existent
  92. memory as strings of dots (and doesn't disassemble it).
  93.  
  94.  
  95. MemoryA
  96. -------
  97.  
  98. In interactive mode, it won't cross over into non-existent memory.
  99.  
  100.  
  101. ShowRegs
  102. --------
  103.  
  104. Is affected by the APCS-R registers flag (see below).
  105.  
  106.  
  107. DisassemblerFlags
  108. -----------------
  109.  
  110. Allows you to set various MemoryI and Debugger_Disassemble features.
  111. Available switches:
  112.     -FDwithR13      use FD with R13, eg. STMDB R13 -> STMFD R13
  113.     -APCS      use APCS-R register set and recognise C function entry
  114.     -LFMstack      use stack notation with LFM & SFM where possible
  115.     -LFS      use LFS and SFS in preference to LFM & SFM
  116.     -QuoteSWIs      put quotes around SWI names
  117.     -UseDCD      use DCD instead of 'Undefined instruction', and BRK where
  118.             DCD &x6000010 would be used
  119.     -UseVDU      use VDU x instead of SWI OS_WriteI+x
  120.     -ANDEQasDCD      use DCD instead of ANDEQ, MOV Rn,Rn (same register) etc.
  121.     -UseADRL      use ADRL/ADRX instead of ADR then ADD/SUB on same reg
  122.     -UseADRW      use ADRW instead of ADD/SUB Rn,R12,#m and LDRW, STRW,
  123.             LDRBW, STRBW instead of xxxx Rn,[R12,#m]
  124.     -LongMul      append L to UMUL, UMLA, SMUL, SMLA (thus using the
  125.             'official' forms)
  126.     -UseLDRL      use LDRL instead of ADD/SUB Rn,Rm,#o + LDR Rn,[Rn,#p] and
  127.             ADD/SUB Rm,Ra,#o + LDR Rn,[Ra,#p]! and STR instead of
  128.             equivalent STRs.
  129.             (The LDRWL form is enabled by this *and* UseADRW)
  130.     -UseNOP      use NOP instead of MOV R0,R0
  131.     -OldPSR      use the old PSR suffixes _ctl, _flg, _all
  132.     -Wide      disassemble for wide display
  133.     -HSLO      use HS and LO instead of CS and CC
  134.     -Shift      use x<<y comments where possible for numbers >= 8192.
  135.             This affects arithmetic and logic instructions. y is
  136.             restricted to multiples of 4 if possible, unless x=1
  137.     -Lower      force all register names to lower case
  138.     -ConstShift   display non-standard constant (x ROR y) as #x,y
  139.             This affects arithmetic and logic instructions with
  140.                     constants for which a simpler representation is possible,
  141.                     e.g. 16 ROR 2 == 4 ROR 0.
  142.  
  143. All the switches take a single character parameter: "0" or "N" (off), or "1"
  144. or "Y" (on). To leave a switch unchanged, don't include it in the command.
  145.  
  146. Use *DisassemblerFlags on its own to display the current state.
  147.  
  148.  
  149.  
  150. The SWI interface
  151. =================
  152.  
  153. Debugger_Disassemble
  154. --------------------
  155.  
  156. Replaces the 'standard' version. Use it in exactly the same way.
  157.  
  158.  
  159. Debugger_DisassembleThumb
  160. -------------------------
  161.  
  162. Not implemented.
  163.  
  164.  
  165. Debugger_Flags
  166. --------------
  167.  
  168. (Also known as Debugger_63 for backward compatibility with Disassembler.)
  169.  
  170. Used to alter the Debugger_Disassemble flags (listed above).
  171.  
  172. Input  : R0 = BIC mask, R1 = EOR mask
  173. Process: new_flags = (old_flags AND NOT R0) EOR R1
  174. Output : R0 = old_flags, R1 = new_flags
  175.  
  176. Bits in R0 and R1 are:
  177.  0 = FDwithR13    4 = QuoteSWIs     8 = UseADRL  12 = UseNOP  16 = Shift
  178.  1 = APCS    5 = UseDCD     9 = UseADRW  13 = OldPSR  17 = Lower
  179.  2 = LFMstack    6 = UseVDU    10 = LongMul  14 = Wide       18 = ConstShift
  180.  3 = LFS    7 = ANDEQasDCD    11 = UseLDRL  15 = HSLO
  181.  
  182. Bits 19 to 22 are currently unused (reserved for future expansion); bit 23 is
  183. reserved for use by Zap and other syntax-colouring editors (lower case
  184. condition codes). Bits 24 to 31 are used internally and cannot be altered.
  185.  
  186.  
  187. Debugger_CPU
  188. ------------
  189.  
  190. Read or write the CPU type (for disassembly purposes).
  191.  
  192. In:  R0 = -1 to read
  193.       0 for the default (the installed CPU)
  194.      >0 to set the CPU type:
  195.         2, 250        ARM2, ARM250
  196.         3        ARM3
  197.         6, 610        ARM610
  198.         7, 700, 710    ARM700, ARM710
  199.         &5A        SA110
  200.  
  201. Out: R0 = CPU type (2, 3, 6, 7 or &5A) if reading, else corrupt
  202.  
  203.  
  204. Debugger_DisassemblePlus
  205. ------------------------
  206.  
  207. An extended version of Debugger_Disassemble.
  208.  
  209. In:  R2 = flags (b0-23) and CPU type (b24-31, as read using Debugger_CPU).
  210.           The CPU type may be 0; if so, the installed CPU type is used.
  211.  
  212.  
  213.  
  214. Disassembly extensions and changes
  215. ==================================
  216.  
  217. MOV R0,R0    Optionally disassembled as NOP
  218.  
  219. MOV PC,PC    Always disassembled as MOV PC,PC
  220.         Sometimes used instead of a branch instruction:
  221.             LDR    R0,data
  222.             MOV    PC,PC
  223.         .data    DCD    &123456        ; this is ignored
  224.             LDR    R1,[R0]
  225.  
  226. SWP        Now listed as 'ARMv2a and later'
  227.  
  228. STM        Warning if base register second or later in register list and
  229.         writeback enabled: 'Base not first in list'
  230.  
  231. ADRL        ADR followed by ADD/SUB with same condition on same register.
  232.         For example,
  233.             00010000    ADRLS    R0,&00010100
  234.             00010004    ADDLS    R0,R0,#&A000
  235.         becomes
  236.             00010000    ADRLS    R0,&00010100
  237.             00010004    ADRLSL    R0,&0001A100
  238.  
  239. ADRX        ADR followed by two ADD/SUBs with same condition on same
  240.         register.
  241.  
  242. ADRW        R12 relative: ADD/SUB Rn,R12,#m
  243.  
  244. LDRW, LDRBW,    R12 relative: LDR/LDRB/STRB/STRB Rn,[R12,#m]
  245. STRW, STRBW
  246.  
  247. LDRL, LDRBL    Without writeback:
  248.             Normal:
  249.             ADD/SUB        Rn,Rm,#o
  250.             LDR/LDRB    Rn,[Rn,#p]
  251.             ->    ADD/SUB        Rn,Rm,#o
  252.             LDRL/LDRBL    Rn,[Rm,#o+p]
  253.             PC relative:
  254.             ADR        Rn,a
  255.             LDR/LDRB    Rn,[Rn,#p]
  256.             ->    ADR        Rn,a
  257.             LDRL/LDRBL    Rn,a+p
  258.         With writeback:
  259.             ADD/SUB        Rm,Rm,#o
  260.             LDR/LDRB    Rn,[Rm,#p]!
  261.             ->    ADD/SUB        Rm,Rm,#o
  262.             LDRL/LDRBL    Rn,[Rm,#o+p]!
  263.         Store address in third register:
  264.             Normal:
  265.             ADD/SUB        Ra,Rm,#o
  266.             LDR/LDRB    Rn,[Ra,#p]!
  267.             ->    ADD/SUB        Ra,Rm,#o
  268.             LDRL/LDRBL    Rn,{Ra},[Rm,#o+p]
  269.             PC relative:
  270.             ADR        Ra,a
  271.             LDR/LDRB    Rn,[Ra,#p]
  272.             ->    ADR        Ra,a
  273.             LDRL/LDRBL    Rn,{Ra},a+p
  274.  
  275. STRL, STRBL    Without writeback:
  276.             Normal:
  277.             ADD/SUB        Rm,Rm,#o
  278.             STR/STRB    Rn,[Rm,#p]
  279.             ->    ADD/SUB        Rn,Rm,#o
  280.             STRL/STRBL    Rn,[Rm,#o+p]
  281.             (followed by a cancelling SUB/ADD)
  282.             PC relative:
  283.             Is not practical
  284.         With writeback:
  285.             ADD/SUB        Rm,Rm,#o
  286.             STR/STRB    Rn,[Rm,#p]!
  287.             ->    ADD/SUB        Rm,Rm,#o
  288.             STRL/STRBL    Rn,[Rm,#o+p]!
  289.         Store address in third register:
  290.             similar to LDRL/LDRBL
  291.  
  292. LDRWL,        R12 relative:
  293. LDRBWL,            ADD/SUB        Rn,R12,#o
  294. STRWL,            LDR/LDRB    Rn,[R12,#p]
  295. STRBWL        ->    ADD/SUB        Rn,R12,#o
  296.             LDRWL/LDRBWL    Rn,o+p
  297.         & similar for 3rd register variants (see LDRL)
  298.  
  299. MCR, MRC    Constant (following first comma) now displayed correctly
  300.  
  301. MRS, MSR    Added for ARMv3 and later
  302.  
  303. UMUL, SMUL,    Added for ARMv3M and later
  304. UMLA, SMLA    (Long 'official' forms supported)
  305.  
  306. LDFxW, STFxW    R12 relative LDF/STF ('x' = precision code)
  307.  
  308. LFM, SFM    Extended format - for example,
  309.             LFM    F1,3,[R13],#&024    ; =36
  310.         may be shown 'as is' or as any of
  311.             LFMIA    F1,3,[R13]!
  312.             LFMFD    F1,3,[R13]!
  313.             LFSIA    R13!,{F1-F3}
  314.             LFSFD    R13!,{F1-F3}
  315.  
  316. FLT        Registers shown correct way round - Fx,Ry instead of Ry,Fx
  317.  
  318. LDC, STC    L and T flags shown in order TL to avoid confusion with the
  319.         LT condition. The T flag is not supported in current versions
  320.         of FPEmulator; it is always used as the writeback bit, and
  321.         must therefore be set for the post-indexed forms.
  322.         (This also affects LDF, STF, LFM and SFM.)
  323.  
  324. VDU, VDUX    Equivalent to SWI OS_WriteI and XOS_WriteI respectively
  325.  
  326. LDR, STR    H, SH, SB forms added for ARMv4 and later
  327.         W (R12-relative) forms supported, eg. LDRSBW R0,&40
  328.  
  329. Instructions which rely on PC plus implied offset, because of the possibly
  330. different values of this offset for different ARM implementations, are
  331. flagged as "*** Offset not guaranteed". With APCS support enabled, this
  332. comment will not be appended to STMFD instructions which are part of C
  333. function entry sequences.
  334. (comp.sys.arm <47kr75$hpc@doc.armltd.co.uk>, David Seal, "Re: Storing PC")
  335.  
  336. The APCS support cannot distinguish between the R and M variants;
  337. fortunately, there appears to be no need to do so.
  338.  
  339. LDRs and STRs which are PC-relative always appear in the standard form. For
  340. an instruction pair in which the first is of the form "[Rm],#d" and the
  341. second is an ADD or SUB modifying (and storing in) Rm, a comment "Rm+=x" will
  342. be shown.
  343.  
  344. Comments of the form '="x"' now contain the character code: '="x" (120)".
  345.  
  346. Constants which the BASIC assembler won't get right (eg. 256 stored as 4 ROR
  347. #26, rather than 1 ROR #24) are flagged as such.
  348.  
  349.  
  350.  
  351. Known 'features'
  352. ================
  353.  
  354. None (at the time of writing).
  355.  
  356.  
  357.  
  358. And finally
  359. ===========
  360.  
  361. As with all good software, there may be undocumented features... let me know
  362. and I'll try to fix them.
  363.